Skip to content

feat: add file navigation mappings to jump to file under cursor from terminal - #676

Open
franckspike wants to merge 1 commit into
akinsho:mainfrom
franckspike:feat/goto-file-under-cursor
Open

franckspike wants to merge 1 commit into
akinsho:mainfrom
franckspike:feat/goto-file-under-cursor

Conversation

@franckspike

@franckspike franckspike commented Oct 16, 2026 •

Copy link
Copy Markdown

Description :

Problem

When running compilers, tests, linters, or scripts in ToggleTerm, terminal output frequently displays stack traces and error locations with file paths, line numbers, and column numbers (e.g., src/main.rs:42:10 or File "app.py", line 42).

Navigating back to the exact file and line in the editor currently requires closing the terminal, manually editing the file path, and jumping to the line.

Solution

This PR adds an opt-in navigation configuration that provides smart file-jumping directly from terminal buffers in normal mode:

  • Token & coordinate parsing: Automatically extracts file path, line number, and column number from under the cursor.
  • Broad format support:
    • path/to/file:line:col (e.g., src/main.rs:42:15)
    • path/to/file:line (e.g., src/main.rs:42)
    • path/to/file
    • Python stack traces (File "app.py", line 42)
    • Git diff paths (strips a/ or b/ prefixes if the stripped file exists)
  • Window selection:
    • Integrates with s1n7ax/nvim-window-picker if installed to pick the destination window.
    • Automatically falls back to the previously active window (wincmd p).
  • Configurable split orientation:
    • Automatically opens a split if requested or if the target buffer has unsaved changes.
    • Supports split_direction = "vertical" (default) or "horizontal".
  • Auto-close: Optionally closes or hides the active terminal once the file is opened (close_terminal = true).
  • Fully opt-in: navigation.enabled = false by default for 100% backward compatibility.

Configuration

require("toggleterm").setup({
  navigation = {
	enabled = true,
	use_picker = true,             -- use s1n7ax/nvim-window-picker if installed
	open_mapping = "gf",           -- open in target window
	split_mapping = "gF",          -- open in split
	direct_mapping = "<leader>gf", -- open directly in previous window without picker
	split_direction = "vertical",  -- "vertical" | "horizontal"
	close_terminal = true,         -- close/hide terminal after opening file
  },
})

──────

Commands & Lua API

• User commands:
• :ToggleTermOpenFile : open file under cursor in target window.
• :ToggleTermOpenFileSplit [vertical|horizontal] : open file in a split (direction can be overridden via argument).
• Lua API:
• require("toggleterm").open_file(opts)
• require("toggleterm.navigation").get_file_under_cursor(line, col)

──────

Checks

[✓] Tested locally with unit tests (tests/navigation_spec.lua).
[✓] All 58 Plenary tests passing (make test).
[✓] Options and usage documented in README.md.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant